Support `isinstance` constraints in inference #2846

zenlyj · 2025-10-04T15:35:06Z

Type of Changes

	Type
	🐛 Bug fix
✓	✨ New feature
	🔨 Refactoring
	📜 Docs

Description

These changes implements the constraint interface to add a new constraint - TypeConstraint to improve the accuracy of inference for objects used in type-narrowing guards.

Currently, the implementation only supports the isinstance pattern, but it should be relatively straightforward to extend it to support the negated case (not isinstance) in the future.

To determine whether an object is an instance of the given types, the implementation reuses existing inference mechanism for isinstance in brains.

Refs pylint-dev/pylint#1162
Refs pylint-dev/pylint#4635
Refs pylint-dev/pylint#10469

codecov · 2025-10-04T15:41:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.39%. Comparing base (4a7e23f) to head (3bcec6b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2846      +/-   ##
==========================================
+ Coverage   93.35%   93.39%   +0.04%     
==========================================
  Files          92       92              
  Lines       11190    11208      +18     
==========================================
+ Hits        10446    10468      +22     
+ Misses        744      740       -4

Flag	Coverage Δ
linux	`93.26% <100.00%> (+0.04%)`	⬆️
pypy	`93.39% <100.00%> (+0.04%)`	⬆️
windows	`93.37% <100.00%> (+0.04%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
astroid/brain/brain_builtin_inference.py	`92.68% <100.00%> (+0.65%)`	⬆️
astroid/constraint.py	`100.00% <100.00%> (ø)`
astroid/helpers.py	`95.56% <100.00%> (+0.23%)`	⬆️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

zenlyj · 2025-10-04T15:48:41Z

Seems like test coverage is lacking. Shouldn't be an issue to get it up to 100%, but I would like a review first to see if this implementation makes sense.

jacobtylerwalls

Wonderful!

As we do more of these, it would be nice to add a CI step that installs pylint and runs the primer. I had an experiment (work in progress) at jacobtylerwalls#157 and
pylint-dev/pylint@main...jacobtylerwalls:pylint:run-with-custom-astroid. Something for later.

astroid/constraint.py

tests/test_constraint.py

DanielNoord

@jacobtylerwalls Should this be merged for 4.0.0 considering we already released a RC? Feels like a big change to include after a RC.

jacobtylerwalls · 2025-10-04T19:24:43Z

I wondered as well, happy to wait for 4.1. Let's release 4.0 final tomorrow in that case.

DanielNoord · 2025-10-04T19:26:37Z

I wondered as well, happy to wait for 4.1. Let's release 4.0 final tomorrow in that case.

Let's do so, especially as we haven't tested this with pylint yet. 4.0.0 has enough new features already :)

Pierre-Sassoulas

This is neat ! Glad to see that the constraint api is getting some love.

zenlyj · 2025-10-12T08:35:40Z

astroid/helpers.py

+    except StopIteration as e:
+        raise InferenceError(node=node, context=context) from e
+    # arg2 MUST be a type or a TUPLE of types
+    # for isinstance
+    if isinstance(node_infer, nodes.Tuple):
+        try:
+            class_container = [
+                next(node.infer(context=context)) for node in node_infer.elts
+            ]
+        except StopIteration as e:
+            raise InferenceError(node=node, context=context) from e


The StopIteration handlers are not covered by tests, wondering if it is reasonable to exclude them. From what I understand .infer() already throws InferenceError and we won't get to these blocks?

Isn't it possible for node.infer(context=context) to be inferable but an empty iterable ?

That was what I thought as well, but when we get an empty iterable, this decorator catches StopIteration and raises InferenceError? Not sure if there are cases where this decorator is not used.

astroid/astroid/decorators.py

Lines 75 to 96 in ab119c2

def raise_if_nothing_inferred(

func: Callable[_P, Generator[InferenceResult]],

) -> Callable[_P, Generator[InferenceResult]]:

def inner(*args: _P.args, **kwargs: _P.kwargs) -> Generator[InferenceResult]:

generator = func(*args, **kwargs)

try:

yield next(generator)

except StopIteration as error:

# generator is empty

if error.args:

raise InferenceError(**error.args[0]) from error

raise InferenceError(

"StopIteration raised without any error information."

) from error

except RecursionError as error:

raise InferenceError(

f"RecursionError raised with limit {sys.getrecursionlimit()}."

) from error

yield from generator

return inner

Not sure if there are cases where this decorator is not used.

That worries me also (plugins?)

A pragma to exclude coverage seems reasonable.

I excluded coverage for those blocks, it is worth noting that they were previously uncovered as well. These changes only shift the method to a different file.

zenlyj · 2025-10-12T08:44:23Z

astroid/constraint.py

+            matches_checked_types = helpers.object_isinstance(inferred, types)
+
+            if matches_checked_types is util.Uninferable:
+                return True


This Uninferable check is not covered by tests, it should be unreachable in runtime. I am including it as a safe guard because helpers.object_isinstance() returns bool | Uninferable, but I am also fine with removing it. Thoughts?

Can you share more details about why this is unreachable? I see that we short-circuit if inferred is uninferable, but it wasn't apparent to me why inferring again wouldn't return uninferable.

Looked into object_isinstance(), there are two main cases where it can return Uninferable:

When the type of the object cannot be inferred, happens when:

The object resolves to multiple types. This should not occur since inferred is an item within a list of inferred results.

Inference error is raised while doing inferred.infer(). This may occur when inferred itself is Uninferable, but as you mentioned there is already a short-circuit check above.

When the type can be inferred but is not an instance of nodes.ClassDef. However, it seems that the inferred type always appears to be a ClassDef, or wrapped in a ClassDef proxy.

This should not occur since inferred is an item within a list of inferred results.

That's what I'm unsure about, inferring an item may return something besides itself.

Trying to think of a scenario where inferring a non-Uninferable inference result returns multiple results. Not sure if that's a common case but I'd be interested to know if you have any concrete examples in mind.

An alternative is to mock the method to return Uninferable:

def test_isinstance_uninferable(): node = builder.extract_node( """ x = 3 if isinstance(x, str): x #@ """ ) with patch.object(helpers, "object_isinstance", return_value=Uninferable): inferred = node.inferred() assert len(inferred) == 1 assert isinstance(inferred[0], nodes.Const) assert inferred[0].value == 3

I'm good with that. Sorry I don't have the time to construct a concrete example.

No worries, I will go with the mocking approach for now. If anyone has encountered this before, feel free to chime in!

for more information, see https://pre-commit.ci

zenlyj added Enhancement ✨ Improvement to a component inference labels Oct 4, 2025

jacobtylerwalls previously approved these changes Oct 4, 2025

View reviewed changes

astroid/constraint.py Outdated Show resolved Hide resolved

tests/test_constraint.py Show resolved Hide resolved

jacobtylerwalls added this to the 4.0.0 milestone Oct 4, 2025

DanielNoord reviewed Oct 4, 2025

View reviewed changes

Pierre-Sassoulas previously approved these changes Oct 5, 2025

View reviewed changes

Pierre-Sassoulas modified the milestones: 4.0.0, 4.1.0 Oct 5, 2025

Pierre-Sassoulas added the Blocked 🚧 A PR or issue blocked by another PR or issue label Oct 5, 2025

zenlyj dismissed stale reviews from Pierre-Sassoulas and jacobtylerwalls via b3b9dd4 October 12, 2025 08:20

zenlyj force-pushed the constraint-type branch from e5217a2 to b3b9dd4 Compare October 12, 2025 08:20

zenlyj commented Oct 12, 2025

View reviewed changes

zenlyj force-pushed the constraint-type branch from b3b9dd4 to 010503c Compare October 12, 2025 09:37

zenlyj and others added 7 commits October 18, 2025 12:41

Implement type constraint

27f14a7

Add tests

f7b9b2b

Add changelog

4d65ad7

[pre-commit.ci] auto fixes from pre-commit.com hooks

925ffef

for more information, see https://pre-commit.ci

Use identity checks

820e078

Add more tests

f19e9bf

Exclude StopIteration handlers from coverage

16032d5

zenlyj force-pushed the constraint-type branch from 010503c to 16032d5 Compare October 18, 2025 10:21

zenlyj and others added 2 commits October 20, 2025 01:01

Add test case for uninferable isinstance

d44dae8

[pre-commit.ci] auto fixes from pre-commit.com hooks

3bcec6b

for more information, see https://pre-commit.ci

jacobtylerwalls approved these changes Oct 19, 2025

View reviewed changes

	def raise_if_nothing_inferred(
	func: Callable[_P, Generator[InferenceResult]],
	) -> Callable[_P, Generator[InferenceResult]]:
	def inner(args: _P.args, *kwargs: _P.kwargs) -> Generator[InferenceResult]:
	generator = func(args, *kwargs)
	try:
	yield next(generator)
	except StopIteration as error:
	# generator is empty
	if error.args:
	raise InferenceError(**error.args[0]) from error
	raise InferenceError(
	"StopIteration raised without any error information."
	) from error
	except RecursionError as error:
	raise InferenceError(
	f"RecursionError raised with limit {sys.getrecursionlimit()}."
	) from error

	yield from generator

	return inner

Uh oh!

Support isinstance constraints in inference #2846

Are you sure you want to change the base?

Support isinstance constraints in inference #2846

Uh oh!

Conversation

zenlyj commented Oct 4, 2025

Type of Changes

Description

Uh oh!

codecov bot commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

zenlyj commented Oct 4, 2025

Uh oh!

jacobtylerwalls left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DanielNoord left a comment

Choose a reason for hiding this comment

Uh oh!

jacobtylerwalls commented Oct 4, 2025

Uh oh!

DanielNoord commented Oct 4, 2025

Uh oh!

Pierre-Sassoulas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zenlyj Oct 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Support `isinstance` constraints in inference #2846

Support `isinstance` constraints in inference #2846

codecov bot commented Oct 4, 2025 •

edited

Loading

zenlyj Oct 19, 2025 •

edited

Loading